b.stefanuk.ca

Appearance

Writing Design Documents ​

This document is part of a series on my repeatable process for creating great products. After the Product Spec comes the Design Document.

Software Design Document (SDD) ​

Design documents are created to coordinate efforts of a large team, give them a stable reference point, and describe all parts of the software and how they will operate.

For any project that will take longer than a month, you should create an SDD before you start coding.

Software Design Documents (SDDs) are crucial during the development of new software systems: they clarify the intention behind a new software's design, give direction to the development process, and expose data structures, dependencies, and requirements that may not be immediately apparent. Software design documents force the architect to think through the entire system, thereby exposing gaps in thinking, or steps missing the in conceptualization phase.

Hint

An SDD has two main components (i) the finished software's functionality and design, and (ii) the roadmap to build it.

Before getting started, make sure there is a Product Spec, if not, then make sure that there is a higher-level description of what is being produced. The SDD is a developer-focsed document that sets the foundation for how a product or solution is to be created at a system and component level. Keep it simple; minute details of the solution should ideally be documented in place (in the code) or there should be a more comprehensive Technical Spec (but write it alongside the development of the system, not before, otherwise it will be a version control nightmare).

SDD Template ​

Introduction ​

  • Example one-liner to get you started: "[What the system does] is crucial when [problem the system solves]. This is the job of the [name of the system], and it has the following responsibilities: [list at least 3 key responsibilities of the system]"
  • You may expand on the above one-liner, but make sure to address:
    • Context:
    • Problem being solved: What problem will the software solve?
    • System overview: Description of the system and functionality of the software

Context OR Background

  • Why the system is needed?
  • Is it a re-write or has it been developed by others? If applicable, what are the shortcomings of current implementations.
  • What is the history of this solution within the organization?

Features AND/OR Requirements

  • Depending on the nature of the project, you may want to include either one or the other, or both features and requirements.
  • List all of the obvious features/requirements of the system. Don't over do it, you can refined these as you gather feedback. This is a good way to engage the team and let them feel like they're contributing.
Vision, constraints, requirements

A personal touch I often use to clarify requirements is the use the Vision, Constraints, Requirements combo whereby the Vision (ideal solution) and the Constraints (limitations on achieving the vision) spawn the requirements of the system.

System Overview ​

  • Add a simple diagram of the system. You can start with a system-level layered design, or start by creating blocks that represent potential system components. Then, start connecting them. Think about how the component can be grouped into layers. Add any databases, network connections, or user interfaces/input.
  • Next add a paragraph description of the system, outlining any gaps that aren't provided in the diagram. Supplement the diagram here, don't just describe it. Again, keep it simple.
  • Add a final sentence such as: "The system is broken down into [N] layers, the [X] Layer, ..., and [Y] Layer. Together, these form the fundamental structure of the system, as shown in the following diagram.

User Interface OR Usage

  • What will the final product look like? Use wireframes.
  • If there's no UI or it's a developer tool, then describe its usage, APIs? Command line?

Detailed Design ​

  • This is the most detailed section of the document and should include diagrams.
  • Make a section for each of the layers from the System Overview. Add a proposed class diagram for core components or each layer. If it's too hard to create a class diagram, add references to existing systems or make a simple flowchart.

X Layer

  • Quick description and responsibilities
  • List all of the components of the X layer
  • Add a class diagram and a caption like: "Below is a diagram of the proposed strategy for the X Layer."

Y Layer

  • Quick description and responsibilities
  • List all of the components of the Y layer
  • Add a class diagram and a caption like: "Below is a diagram of the proposed strategy for the Y Layer."

Data Flow

  • "The diagram below demonstrates the proposed data flow through the system."
  • For a primer on how to create good data flow diagrams, see UML Diagrams Simplified.

Auxillary Components

  • "In addition to the primary components listed above, the following are implemented as supporting objects"
  • Describe any components that may need to be implemented but don't fit cleanly into the layer architecture above.

Considerations on Solution

  • This should outline alternative solutions, potential blockers in the development process, and any open questions pertaining to the proposed solution.
  • What have you (maybe willfully overlooked)?
  • What knowledge gaps still exist within the design?
  • What are the biggest risks?

Testing and Stability ​

  • Is unit testing going to require mocks? Or will it be straight forward?
  • How about integration testing?
  • How will functional testing be different than unit/integration testing? Will there need to be a simulation? In what ways will it be from different than running in production?
  • Say: "Unit and integration testing is be carried out as part of the standard CI/CD testing infrastructure. Code coverage is maintained above 90% to ensure that all nominal and known edge cases are handled correctly."

Test cases:

  • Write all obvious test cases, both success and failure. Don't overdo it, you can refined these as you gather feedback.
  • Example: "Inbound account update request for a registered user; returns success reply"

Error conditions:

  • What error conditions do you expect to face? What edge cases might the developer overlook when creating the system? Name at least three, it makes you seem smart.

Recovery measures:

  • How do you intend to recover if the system crashes or begins operating in a faulty state?

Safety measures (only for critical applications):

  • How do you intend to keep people and hardware safe from harm in the case of malfunction? What considerations are you making? What assumptions are you making?

Milestones OR Goals AND Roadmap ​

  • Clients, developers, literally everyone wants to know the roadmap. It's crucial to outline when things are expected to be finished, and with what resources. It's also crucial to try and be as accurate/realistic a possible.
    1. You can use a literal timeline, or a Gantt chart or something.
    2. Have concrete, measurable milestones

Appendix ​

  • Define technical terms
  • List third-party dependencies of the system
  • List related resources and documentation

How to Write Requirements ​

It is recommended to stick the conventional terms "shall", "will", and "should". Always define these terms within the document.

  • Shall is used to specify a contractually binding requirement. A "shall" statement must be implemented and verified. If it doesn't have "shall" then it isn't a requirement.
  • Will is used to indicate a statement of fact. A "will" statement doesn't need to be verified. It can be used to describe how a system will work, function, or standards it will abide by.
  • Should is used to specify a feature that must be addressed by the engineering/design team, but isn't subject to express verification. These are useful for critical considerations, but don't need to be verified in the same way as a requirement.

Closing Thoughts ​

  • Use simple language, focus on understandability, not on using $5 words.
  • Use visuals religiously, nobody ever complains about there being too many good diagrams and visual descriptions. A picture's worth 1000 words.
  • Get feedback early.
  • Keep you Software Design Document up-to-date.

It can be a good idea to include a prioritization matrix (Eisenhower matrix) which plots urgency vs. importance into quadrants. Use the quadrants to decide what to include in your Minimum Viable Product.

RESOURCES ​